email from Tom Johnson (Jekyll them developer)

email_chaing_tom_johnson_jekyll_theme_dev.txt

Sweet!


---------- Forwarded message ----------
From: Tom Johnson <tom@idratherbewriting.com>
Date: Mon, Jan 22, 2018 at 6:31 PM
Subject: Re: Consultation re: documentation-theme-jeykll
To: Jennifer Lindner <jenlindner@gmail.com>


Re content development, try reaching out to Tia. I've met her and she seems
capable and eager to build her portfolio through volunteer doc work. Here's
the message she sent me:


Hi Tom,

Hoping you are well!

As a reminder we met at iHop when you taught API documentation to the STC
group. Thank you again for making yourself available in that way.

I am writing share that I am available to volunteer time to anyone who might
like to offload some API documentation work. My objective is to gain hands-on
experience so that I can 1) ensure I like it and 2) land a full time role as
an API Technical Writer in the next three to six months.

I am looking around to get certified; if you have course recommendations feel
free to let me know. (I am currently enrolled with LinkedIn Learning.)

With sincerity, I would like to thank you again for your thoughtful, hands-on
teaching methods with API documentation. You have made this intimidating
"foreign language" very accessible.

As an aside, I just read GitHub's "REST API v3 Getting Started" page last
night. The best part, aside from the clarity, was the humor the writer
sprinkle into the document. Wow, humor...what a concept!

Once again,if you know of anyone who might like an API documentation
volunteer, you know where to find me.

Wishing you and your family the warmest and happiest of holidays.

All the best,


Tia Marciel
Technical Writer
tia.marciel@gmail.com
(408) 348-6708 mobile (text or call if you like)


=========================================

Hi Tom, I just want to underscore that we are looking for content management
help besides some tech help, we need some editorial help wrangling the
materials we have and are expecting to get in. Do you know anyone you might
recommend for that aspect, or know a good place to ask around to find people?
Write the Docs seems like a good source...

Thanks,
Jennifer, Drew's fellow Samvera community member

=========================================

On Mon, Jan 22, 2018 at 5:12 PM, Andrew Myers <andrew_myers@wgbh.org> wrote:
Hi Tom,

Thanks for your thorough response and suggestions. If you happen to know any
Jekyll theme developers willing to work for hire, we'd be inerested in getting
in touch.

In the meantime, we'll explore your suggestions more closely. Do you happen to
have a link to a site that is using your new theme? If that's a light lift,
and can give us 3 layers of navigation, then we will probably give that a try.
I also like the idea of Navtabs for versions. That seems a bit cleaner than
what we're currently doing.

Thanks for your time and advice!
Drew

=========================================

From: Tom Johnson <tom@idratherbewriting.com>
Date: Wednesday, January 10, 2018 at 12:21 PM
To: Andrew Myers <andrew_myers@wgbh.org>
Cc: "jenlindner@gmail.com" <jenlindner@gmail.com>
Subject: Re: Consultation re: documentation-theme-jeykll

Hi Andrew, sorry for the delayed response. Glad to see that you're digging
into Jekyll. Re adding another level of navigation, I actually have another
doc theme here -- https://github.com/amzn/jekyll-doc-project -- that I'm going
to replace the existing theme with. I believe this other theme has the
additional levels you're seeking. Not sure if you wanted to use it instead,
because there are some other changes you'd have to make in the
includes/sidebar file (https://github.com/tomjoht/documentation-theme-
jekyll/blob/gh-pages/_includes/sidebar.html). But foundationally the code is
much better.


Anyway, to hack in another level into the existing theme wouldn't be too hard,
but there are associated styling needs that accompany it as well. Just to make
sure, you saw the full extent of the levels in the existing theme, right? For
example, if you look here http://idratherbewriting.com/documentation-theme-
jekyll/tag_formatting.html, you'll see the full depth it currently provides.
Why would you want more hierarchy than that? To some extent, the code
limitations help enforce best practices. You want to enable users to see the
whole at a glance. if you embed too much hierarchy, you eliminate that
benefit.


Re versions, I don't have any explicit support for versions or a strategy
recommended. You could use Navtabs (http://idratherbewriting.com
/documentation-theme-jekyll/mydoc_navtabs.html), but then you'd have to write
the content in HTML. I haven't really thought much about the best approach for
versioning docs. I'm sorry that I don't have any more immediate guidance with
this right off hand. You might want to explore how other doc sites tackle
versions and see what makes the most sense for your content and audience. At
the very least, you could create multiple topics. One thing to keep in mind is
the canonical topic. When people search for your content, how do you guide
them to the right version from the topic they discover from search?


Re more in-depth consultation, I'm super busy at the moment so I can't take on
custom development. However, if you have feature requests I can put them on
the long-term development plan.

============================================

On Tue, Jan 9, 2018 at 10:25 AM, Andrew Myers <andrew_myers@wgbh.org> wrote:

Hi Tom,

We're using your Documentation Jekyll theme from https://github.com/tomjoht
/documentation-theme-jekyll. We've implemented it here:
https://samvera.github.io/.


We are an open source community that has seen a lot of success and buy-in when
it comes to product development, but less so when it comes to documentation.
The Github pages site is our latest community effort to make headway toward a
more comprehensive and maintainable solution.


While our team does not have a lot of experience working with Jekyll themes,
we have been able to train ourselves on the basics. At this time, we have a
couple of requirements we were hoping to get out of your theme, but we could
use some guidance in doing so.


First, we were hoping to add an additional level of navigation in the left
menu. We realize the theme's navigation is only 2 levels deep by design, but
we think that the nature and volume of our content could benefit from a 3rd
level. We're also open to other suggestions on how to reorganize content to
better fit the 2-level navigation we get out-of-the-box.


Second, we would like to allow adding multiple versions of individual pages
(or groups of pages). This need arises from the fact that much of our
documentaiton refers to multiple tools, each with their own semantic version
numbers.


For example, say we have a tutorial that refers to Foo v1.0.0 and Bar v2.0.0,
and let's say that a new verion of Foo, v1.1.0, is released. In this case,
we'd like to have 2 versions of the tutorial: one that refers to Foo v1.0.0
with Bar v2.0.0, and another version that refers to Foo v1.1.0 with Bar
v2.0.0.


Any guidance you have to offer on how to impelement these features using your
theme would be greatly appreciated.


Additionally, we are willing to pay you for a more in-depth consultation,
ideally a few hours or more, provided that your hourly rates fit within our
budget contraints. Please let us know at your earliest convenience.

Sincerely,

Drew Myers (on behalf of the Samvera community's documentation working group)


P.S. I am CC'ing a fellow Samvera community member, so please 'reply all'.
Also, I will likely include this correspondence in our meeting notes which are
publicly available, unless you expressly request otherwise. Thanks!