[Improve Existing Best Practice Guide]: Documentation Organization Ref Architecture

[riverma]

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Documentation

Best Practice Guide Sections

Reference Architectures

Describe the improvement

We need some sample reference architectures for recommending how documentation created for a project should be organized. This involves documentation artifacts like user guides, dev guides, etc., and how they can be organized to make it most efficient for users and developers to find those resources.

[Scotchester]

I don't have a clear idea of how this might fit with your plans and intentions for the SLIM website's content, but I wanted to share this documentation framework that I really like:

https://diataxis.fr/

[riverma]

@Scotchester - I really like the link you shared. It takes a really high-level structural view of the most important components of good documentation. Thank you for the excellent suggestion!

I need to read that link in a bit more in depth, but do you have any suggestions to the current recommended documentation hierarchy based on your reading / understanding you'd like to share?

[Scotchester]

@riverma Sure thing!

I think the Diátaxis framework is most geared toward the developer docs portion of the recommendation in #30. The user docs I would probably suggest keeping entirely separate, but this certainly would depend on the nature of the software and the expectations of its users.

Looking just at the proposed outline of developer docs, here's how I see them correlating with Diátaxis. (For simplicity, I have collapsed the sections for multiple systems into one.)

• Architecture – Explanation
• Features – N/A? More introductory/marketing material than "docs"
• Quick Start – How-to guides
• Docs
  • User Guide – Tutorials
    • Setup
    • Running
    • Usage Examples
  • Developer Guide – How-to guides
    • Requirements
    • Setup
    • Building
    • Running
    • Testing
  • Admin Guide – Not entirely sure what is meant by this, but it feels like Reference
    • Requirements
    • Installing
    • Configuring
    • Troubleshooting
• FAQ – FAQs in documentation feel like a bit of an anti-pattern, in my opinion. I would try to make whatever information one wanted to put here more discoverable in other places.
• Getting Involved – Explanation (if design decisions are discussed) and/or Reference
  • Prerequisites
  • Development Process
  • Ways to Contribute

FWIW, my domain is web development and software that enables that, so that's the lens with which I look at this. While I'm sure there is some overlap, I feel like I would need a primer on the kind of software projects you're primarily concerned with in order to suggest any specific changes to the proposed hierarchy.

[riverma]

@Scotchester - very much appreciate your insights!

Some thoughts:

• Thinking "Admin Guide" would help guide the install and administer phase from a systems admin perspective. From the web-dev perspective, does that just fall under "Developer Docs" or "User Docs"?
• Based on your suggestion - thinking it'd be good to account for the nature of projects Ex: web-projects, backend projects, etc. In fact, we've got another thread discussing how to structure Operational documentation (especially for large-scale data systems) - which is its own beast. One of the goals of this ticket and the associated PR is to recommend a doc structure hierarchy that can be consistently used across member projects for ease of navigation. Maybe even auto-generate a folder hierarchy with template files if people find that useful down-the-line. Creating categories of software projects might be wise in this light.

I think as an initial next step, I may update the PR to make room for (at minimum) three types of doc hierarchies: data-systems / backend docs, front end docs, operational docs. What do you think? Would you be open to collaborating on the front-end docs hierarchy template (or any others)? :).

[Scotchester]

• Thinking "Admin Guide" would help guide the install and administer phase from a systems admin perspective. From the web-dev perspective, does that just fall under "Developer Docs" or "User Docs"?

Gotcha. In web-dev world, I would consider that part of User Docs.

• Based on your suggestion - thinking it'd be good to account for the nature of projects Ex: web-projects, backend projects, etc. In fact, we've got another thread discussing how to structure Operational documentation (especially for large-scale data systems) - which is its own beast. One of the goals of this ticket and the associated PR is to recommend a doc structure hierarchy that can be consistently used across member projects for ease of navigation. Maybe even auto-generate a folder hierarchy with template files if people find that useful down-the-line. Creating categories of software projects might be wise in this light.

I think as an initial next step, I may update the PR to make room for (at minimum) three types of doc hierarchies: data-systems / backend docs, front end docs, operational docs. What do you think? Would you be open to collaborating on the front-end docs hierarchy template (or any others)? :).

Yeah, I think that largely makes sense, and I would be glad to collaborate on the suggested front-end hierarchy (though any serious time spent on that probably needs to wait until late October, given the work I have lined up for end of FY and helping our team present at DjangoCon).

One other thing I would note is that the terms "back end" and "front end" can mean different things to different people, and both are usually needed in the web world – sometimes in one repository, sometimes in separate repositories. I'm not 100% sure I am clear on what you are meaning when you use those terms above, but as an example, the JPL external website has www-backend, www-frontend, and www-terraform repositories. There is definitely room for improvement, but each of these currently has their own documentation in different forms, and all three are necessary to end up with the JPL external website running in AWS as you see it on https://www.jpl.nasa.gov/.

[riverma]

Hi @Scotchester - thanks for the reply. Great to see you're interested! That'll help me set up some of the structure to have a proposed front-end docs hierarchy that future front-end projects can use (including your own or your teammates). I think @tariqksoliman might even be interested in this, as he works heavily in UI.

To answer your question - backend to me means strictly non-user-interface code, akin to a service that can be invoked programmatically. Front end to me is code related to direct user interaction. It's fuzzy. Maybe we should use better names in our own differentiation.

I'll see what sort of structure / template guide I can whip up that can then be filled in later more for the various types of documentation.

[riverma]

+1'd by @nttoole @rtapella @pymonger