Volunteer requesting to help clean up API docs - some points

[micshar92]

Hi, OpenBoxes team. I'm a technical writer with a background in supply chain, and I want to contribute to your documentation because you're in that field and I can stand behind your product ethically. Fair warning: I have to yet to be hired, for pay, as a technical writer— I just have the "book learning" right now, and a few practice experiences. (here's my portfolio, and here's my last open-source contribution, for proof.)

I want to contribute to your API documentation to help me get my foot in the door for my first salaried job. So with that in mind, I've read a lot of best practices, API design, how they work, etc. docs over these past few months. I suggest the following changes to yours. (All up for debate; tell me if you think each is a good idea.)

1. The overview page I think needs to be merged with the getting started page. Maybe rename the "Generic API" title to "Using the Generic API".
2. It's generally best practice to have a "one-pager" because, at least from what I've read developers say, they like to use Ctrl+F to easily find what they're looking for instead of searching through multiple pages with different headings. This doesn't mean ONLY a one-pager— the other conceptual/task pages are important, too.
3. "Authentication and authorization" is a typical page for API docs— you currently have the info on a page that falls under a different header. I think it needs its own page.
4. Maybe a quick reference would be useful? example
5. Maybe a glossary would be useful? example
6. General proofreading of the Swagger API. There are some typographical errors.
7. I might be overstepping my authority here, but I think the very dark blue text that denotes a link is too hard to distinguish from the regular text. The links are not underlined, either, so it's hard to tell (absent context clues) what is a link in the text. If my contributions include links, I think it would be better to make them more visibly distinct than the regular text. I also think that your code samples on all pages would greatly benefit from being color-coded (I can easily set this in the mkdocs.yml). Maybe even change the code block background to black, with color text? When I scroll through the pages, the drab grayness makes the code harder to read and blurs together. But I'd also understand if you want to stick to your brand colors. Let me know what you think.
8. A few small things that don't impact much (for instance, a broken list on the core identifiers page).

I'll follow the procedure in your contributions guide. Just let me know your opinion(s) on these points. Thanks!

[jmiranda]

Thanks @micshar92. We would love some help with the API docs. Fwiw, we'd also love to create postman collection(s) and improve our swagger docs to help users do their own testing on various APIs. So let's discuss if you have any interest in that route.

I'll get back to you once I've had a chance to process all of the suggestions above and think about a good approach here.

[micshar92]

I have used Postman, but not collections. Still, from what I see, it seems intuitive enough to make a good "one-pager," and I could do the proofreading at the same time. I'd be willing to use it. Still, different people have different learning styles— some skip to code samples, some prefer prose— so I'd keep the how-to pages currently on the site to go alongside this "one-pager."

[jmiranda]

Agreed.

The Swagger (OpenAPI) docs and Postman examples would provide a different learning perspective on the API and might not be able to capture some of the nuances (internals) that the docs would be able to cover. So we definitely want to maintain all of these.

I'll respond to your bullets above in the next comment, but just wanted to provide more context on where we are with all of these doc-y things ...

Static API docs

The static API docs are very much out of date and I've noticed that the Generic API doesn't work as well as I thought it did. Especially when creating parent and children (i.e. transaction / transaction entries). So there's some testing we need to do to discover and patch the bugs there. Not something for you to do unless you feel comfortable and want to explore. But we can wait on that

Swagger (OpenAPI) Docs

Here's a link to a discussion about the Swagger docs that we published last year as part of a proof-of-concept project. We haven't updated those docs since then but will be doing some more work on it after the Grails migration project is done later in the fall.
https://community.openboxes.com/t/swagger-docs-yes-swagger-docs/480

Postman

Setting up the postman workspace and collection(s) might require a bit more of a discussion to figure out how to structure it correctly. Eventually, I want to use some collections to allow users for learning manual testing and other collections for performance and penetration testing. But just getting a few API examples out in the world and tying them back to our static API docs would be great.

I created a public workspace (this is just a placeholder - there's nothing useful here at the moment)
https://www.postman.com/jcm62/workspace/openboxes-public/overview

I was also working on a test collection in a separate workspace but didn't get very far. Let me know if you can access this.
https://www.postman.com/jcm62/workspace/openboxes-public/collection/818942-9ab2bb71-a421-4485-a956-41b26d8daaea?tab=authorization

There are a bunch of questions I have about parameterization and authentication that will require more investigation.

Automating API Testing

FWIW, I just bought this book to help improve automated testing for our APIs and I assume it might have some interesting insights on how to write documentation as well.
https://www.manning.com/books/testing-web-apis

[micshar92]

Yes, I can access the workspace just fine. The responses also look good to start.

[jmiranda]

The overview page I think needs to be merged with the getting started page. Maybe rename the "Generic API" title to "Using the Generic API".

Agreed. I think all three of those pages need to have a better structure (info architecture). The current Generic API uses Shipment as the example, but should probably just enumerate the available "resources" and use "resource" as a placeholder. It would be nice to flesh out the structure / hierarchy before making substantial changes just so we make sure we have all of the buckets we need to make the API comprehensible.

Note: I can help with this when I'm back from vacation in a few weeks.

It's generally best practice to have a "one-pager" because, at least from what I've read developers say, they like to use Ctrl+F to easily find what they're looking for instead of searching through multiple pages with different headings. This doesn't mean ONLY a one-pager— the other conceptual/task pages are important, too.

I love this idea. I am hoping that the technology (mkdocs) can provide a way to render both. I know Grails has docs that can be viewed by chapter or all at once.

https://grails.org/documentation.html

Whether basic mkdocs (or any of its templates) allow that is an unknown for me.

"Authentication and authorization" is a typical page for API docs— you currently have the info on a page that falls under a different header. I think it needs its own page.

Yes, absolutely.

Maybe a quick reference would be useful? example

👍 This would be awesome, but probably requires a spike and huddle to evaluate and choose options.

Maybe a glossary would be useful? example

👍 Much needed.

General proofreading of the Swagger API. There are some typographical errors.

👍

I might be overstepping my authority here, but I think the very dark blue text that denotes a link is too hard to distinguish from the regular text. The links are not underlined, either, so it's hard to tell (absent context clues) what is a link in the text. If my contributions include links, I think it would be better to make them more visibly distinct than the regular text. I also think that your code samples on all pages would greatly benefit from being color-coded (I can easily set this in the mkdocs.yml). Maybe even change the code block background to black, with color text? When I scroll through the pages, the drab grayness makes the code harder to read and blurs together. But I'd also understand if you want to stick to your brand colors. Let me know what you think.

I am open to all suggestions.

A few small things that don't impact much (for instance, a broken list on the core identifiers page).

Same as above.

[micshar92]

As for the one-pager, here's an example of the best-practice three-column layout. While it doesn't look to me like either Mkdocs or Grails can accomplish this (and although sometimes companies hand-code (hard!) this layout), all that prettiness goes out the window anyway when viewed on mobile. So I think a plain-old stack layout is fine, like on the Material for Mkdocs site. The layout already on your docs seems good to me, just like I said, with different colors to make it "pop" more.

I think the changes on my fork will go in this order:

1. color changes, authentication and authorization page, proofreading & little fixes
2. glossary (I'll need more terms after the update if you add any, but I can put out a first draft with initial terms)
3. merge overview with getting started page & update generic api page (I'll wait until after your testing)
4. one-pager (but need postman collections first)
5. quick reference guide (high-level, always last)

When are you leaving for vacation? (Have a good one!) I'll save my questions for when you get back and work on the other things until then.

[jmiranda]

This all sounds great. thank you for your help with this.

I started my leave yesterday and will be on vacation (and then home with kids) until school starts September 5. But I can keep tabs so keep me updated.

Two things

• @ me whenever you comment on this ticket or a PR to make sure i get notified
• Create a branch off the feature/upgrade-to-grails-3.3.10 branch (develop and master will be overwritten when we're done with the Grails 3 upgrade)

[micshar92]

Hey @jmiranda. I saw that you're back, so here's an update.

1. (postponed)
2. (postponed)
3. Done. I just copied-and-pasted from the overview page and sewed the seams together.
4. (postponed)
5. Currently working on this; may be a longer project than I anticipated. Will keep you updated.
6. Done.
7. I was in the process of changing the colors for legibility when I noticed that prior to any changes, the mkdocs serve version of the website looks different than the regular website I see when I navigate there. I'm wondering why this is? Because the mkdocs serve version has good colors already, and I think it would be better for legibility. Here's what I mean. The mkdocs serve version:

And the normal, non-testing version (good bold on the table of contents though):

Do you know what's causing this difference?
9. Done.

Ideas

• Add a table of contents to the top of each longer page. The product API page is a good example. This is chiefly because the right sidebar's table of contents disappears when viewed on mobile. It's always best to optimize for mobile, although I'm not sure you get a lot of visitors on mobile.
• I think everything under the "formatting" subheader on the overview page should be its own page. Super easy to do.
• Add a "last edited on: (date)" line to the top of the Swagger specs (people generally value transparency)

[jmiranda]

7. Do you know what's causing this difference?

Regarding the mkdocs issue, it's possible that the versions are all over the place between our local development environment vs what readthedocs uses when deploying the site.

Or maybe the theme config is getting picked up in one place but not another.
https://github.com/openboxes/openboxes/blob/develop/mkdocs.yml#L6

I noticed that I have an old branch (updating our release docs)

and it seems to be using the same theme as your first screenshot.

https://docs.openboxes.com/en/docs-update-release-process/

But I think that's because our old mkdocs.yml config didn't specify the primary and accent palette colors.

https://github.com/openboxes/openboxes/blob/docs-update-release-process/mkdocs.yml#L5

You can play around with the palette config, but I think I made the bgcolor white because our logo looked dumb with blue background.

5. Currently working on this; may be a longer project than I anticipated. Will keep you updated.

Not to complicate matters, but just wanted to let you know that we also have a User Guide that is maintained by Partners In Health. Some of these doc elements (like Glossary) might be more useful or appropriate over there. But we can have that discussion at another time. Getting the bones of a Glossary might be the

https://help.openboxes.com/

[jmiranda]

Add a table of contents to the top of each longer page. The product API page is a good example. This is chiefly because the right sidebar's table of contents disappears when viewed on mobile. It's always best to optimize for mobile, although I'm not sure you get a lot of visitors on mobile.

Yeah, I like that idea. But as you mentioned, we're probably not getting a ton of API docs traffic on mobile. Perhaps we could start a project (https://github.com/openboxes/openboxes/projects) to track all of these tasks on a kanban board. That way you can have a list of tickets that can be prioritized and worked on at your leisure rather than a bullet list in one ticket. What do you think?

I think everything under the "formatting" subheader on the overview page should be its own page. Super easy to do.

Sure.

Add a "last edited on: (date)" line to the top of the Swagger specs (people generally value transparency)

Yes!

[micshar92]

Yes, I think it's a good idea to start a project. I'll likely have little things come up from time to time that I haven't found yet, and I previously authored a pull request with 108 comments on another repo. Which looked weird. So let's make one.

[jmiranda]

@micshar92 Ok sounds good. I'll try to remember to do that next week. In the meantime, I created a new branch to test out some minor changes to the theme (including logo) and navigation, as well as fixing some outdated content and typos. You shouldn't need to take this branch into consideration unless you need some of the config changes.

https://docs.openboxes.com/en/4235-docs-makeover/

[micshar92]

@jmiranda Wow, I didn't even find the knowledge base until you linked to it. I had thought the "User Guide" link under the "Docs" dropdown on the main site linked to this page with the same name, so I never clicked on it. A lot of good stuff in that knowledge base.

But anyway, about the glossary... (here comes another long comment on this page 😵‍💫 )

I initially suggested it because it allows me to show off some coding skills— HTML, CSS, Bootstrap, some JavaScript— since I can say I know these but have no proof on my portfolio. The code is largely in Bootstrap popovers: they have to be initialized with a bit of JavaScript on every page a term is, then they reference a "glossary.yml" on each term to click/select to define. CSS is mild styling, and HTML is the glossary page itself. From my experience, this is best practice.

Largely the point of a glossary is a hyperlink like "see (other page title)" after the definition in the popover. It functions like adding a hyperlinked FAQ in the middle of an article.

However, the problem (and benefit) of glossaries is that every page in the docs has to use the terms as they're defined in the glossary. Glossaries are akin to a style guide. And that's a huge undertaking that's going to have to be across all pages on all guides, if a site wants to have a glossary. Otherwise it crumbles and becomes forgotten, ignored, and useless. It would also have to be displayed prominently, but I'm not sure where yet.

This means that despite all the SEO and reduced customer churn benefits of a glossary...

1. Every docs page, including the guides, wiki, and knowledge base will have to be updated with said popovers and links. If a term appears, or is called something similar but not the same, or is cursorily explained, minor edits to incorporate the terms will have to be done.
2. Every page in the future will need to use the popovers, too, meaning we'd have to add the necessary JavaScript to the contributing guide. For instance, "People" makes a good glossary entry because it's easy to link to the "Manage People" tutorial page from any other page, which also has a definition already on it. Same with "Depot", to a wiki page. But when a new contributor adds a doc page, what will they have to do, go through a list of terms to see if their contribution uses a term on that list, and then copy-and-paste the necessary code into their new page? I think they would find it annoying, or at least a hindrance.
3. It's not possible for me to edit the knowledge base, as far as I know. Same with the wiki pages. Not that I need to edit all the pages, anyway. But I feel a little guilty because in my mind, I seem like a nepotism-hire boss at some business who as soon as he gets in power presumptuously claims they need to change their entire business model.

Because of # 3, I think it may be better to not write a glossary, even though it would benefit us both. Might have bit off more than I could chew here.

Oh, and I like the new theme.

[jmiranda]

Wow, I didn't even find the knowledge base until you linked to it. I had thought the "User Guide" l

We need to do a much better job with info architecture everywhere (openboxes.com, docs.openboxes.com) so any suggestions would be

But anyway, about the glossary...

I agree that the Glossary should be integrated into the docs, but I don't think those two things need to be done at the same time. The glossary ticket can be broken down into at least a few tasks that can be done independently.

• Identify important glossary terms used throughout our docs.
• Define glossary terms (create a page).
• Document process for adding new glossary terms.
• Enhance glossary terms in documentation with glossary feature.
• Identify places where a glossary term should be replaced (this could be a single PR with all suggested changed).

I initially suggested it because it allows me to show off some coding skills— HTML, CSS, Bootstrap, some JavaScript— since I can say I know these but have no proof on my portfolio.

Let's find other ways to make that happen then. openboxes.com probably needs a complete makeover and we're not restricted by mkdocs conventions there. Also, look back through some issues with either the https://github.com/openboxes/openboxes/labels/documentation or https://github.com/openboxes/openboxes/labels/community labels and see if there's anything there that lends itself to expanding on your skills. I'll also try to do a brainstorm or review of old issues that might lead to a fun project.

One idea I've had for a long time is to use typeform, twinery, or some other interactive tool to create a "choose your own adventure" story (or survey) to help people make decisions related to their OpenBoxes adoption. For example, we could start by asking leading questions to help us understand if someone needs a fully managed hosting package or can they do it all themselves. And when they get to the end we can recommend the next steps.

The next steps might be

• make it easier for people to walk through the requirements process (RFP template, upload form, budget analysis)
• figure out a better approach to self-learning content (e.g. improve our Tutorials page to pull in content from youtube, loom, screencastify and other sources)
• allow user to select services they want to purchase like training sessions, implementation packages, etc

[jmiranda]

It's not possible for me to edit the knowledge base, as far as I know.

Me neither. This is another area that I'd like to explore at some point. The software we use for the knowledge base (Helpscout) has a user limit so there's only a handful of people at PIH who can edit the docs.

I'd prefer for the content itself to be open-sourced, even if we were using helpscout or some other knowledge base to publish the guide. In other words, I would love it if there was a tool (like mkdocs) that helped us publish the guide as a knowledge base (with editing, search features, etc) but the content was stored in github.

Anyway, that's probably not a project for right now but just wanted to explain why it's not possible to edit those docs.

[jmiranda]

Here's one other idea related to handling dynamic content on openboxes.com
jmiranda/openboxes-hugo#3

This would be a good way to get use some of the technologies you mentioned earlier.

[micshar92]

@jmiranda Sounds like a good idea, although huge. Anyway, just to keep you updated, I may have figured out a workaround using JSON instead of YAML for the glossary. Very vanilla, should be platform-agnostic. It'll be just for the base site, but I'll still link to the wiki or knowledge base when necessary. More to come soon.

EDIT: Got stuck and asked a StackOverflow question.

[micshar92]

@jmiranda Sorry, but I'm giving up on the glossary popovers. I've spent somewhere around 20 hours researching and trial-and-erroring what I thought would be simple JavaScript. I am completely at a loss, staring blankly at the screen.

The idea was

1. fetch() from a glossary.json file
2. parse() the "title" and "definition", stringify(), store as variable
3. call variable names in title and content of popover

You know, like the tooltips Wikipedia displays when you hover over a link to another article, but with just a term and its definition. No matter what I try, I get this instead.

Where bin_lTerm was the const I declared after the fetch() to be the title "bin location" and bin_lDef the definition.

JavaScript is my weakness. I've been persistent, but I get easily enraged and then exhausted. The sweet spot for learning should be about 7/10 difficulty, but JS for me is a 10, equivalent to theoretical physics. Something about the nebulous, abstract nature of it. Why I can do statistics but not algebra or calculus. Or SQL, Python, HTML, CSS, and the like, but not JavaScript. Concrete nouns in a foreign language, but not unvisualizable things like "implementation." If I can't visualize it, I seriously struggle with it.

I asked my backend developer brother for help, but he told me to run it on Linux and install all the dependencies because Windows is garbage. Then Mkdocs said ERROR - Config value: 'theme'. Error: Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs, and I threw up my hands.

And I still don't know why, but the test page I showed in that picture can't even find the glossary.json in the same folder!!! 😠 I took over an hour on that nonsense. The code is correct!

Oh, I still made the glossary, but the only thing I can do is HTML links to the glossary page. Pathetically easy, and impractical-- who wants to go to that page multiple times in an article? I did everything on the glossary except the code debacle.

I'm not cut out for anything involving JavaScript. If any future employer sees this, sorry. JavaScript is too hard for me.

All this said, I shouldn't have any problem with the other deliverables. Per our discussions above, I'll wait on your tests; I know you're busy. Do you still want me to work on the other deliverables, or pull request what I have now? (it's not much...)

[jmiranda]

I think you just encountered what we like to call "everyone's first experience with JavaScript". You can certainly give up if you'd like. But we also have some terrific JavaScript developers in the community (I am not one of them) who can help you along, provide code reviews and answer any questions that come up.

So create a pull request for what you're working on and I'll get them to take a look next week.

You're not alone. JavaScript is a maddening language to many.

[jmiranda]

Oh and push your branch up when you get a chance. I can try to rejigger the files to get it working.

And include the commands you're running to get the mkdocs error so I know how to reproduce.

[micshar92]

@jmiranda Did a PR for the glossary stuff. Here it is.

As for the Mkdocs issue, that was just my brother telling me to run it on Linux instead of Windows despite it running on Windows just fine. Dunno why he wanted me to do that, but it's entirely on my end and I'm just going to use Windows. No cause for concern.

[micshar92]

@jmiranda Hey! I think it would be easier to close this issue. I'll open separate ones in the future.

Then one last thing: do you have an estimate when you'll have time for the Postman Collections doc? I'm looking forward to it.

[micshar92]

@jmiranda bump

Also, I made a small, easy change to stockMovement.md for #4437, but I can only have one PR open at a time.

[jmiranda]

Thanks @micshar92. We have a bunch of documentation changes to merge as part of the OpenBoxes 0.9.0 release. This is one of those changes. That should be happening soon (in the next week or two).

[micshar92]

@jmiranda While there's a lot of useful and interesting information here, please close this issue. I have another pull request to make. (#4345)