loading...

What do you expect from a good documentation?

sranvir profile image Ranvir Singh ・1 min read

As someone who has little to no experience in web development, I decided to undertake a documentation project for a framework. This seems like a good starting point for me to start thinking from a developer's point-of-view and to reason about things as clearly as possible.

That said, I was wondering if the community can offer me some suggestions as to how do I begin such a task and be of service to the developers who would use the framework after me. Also, I would love to see some more professional efforts at documentation that could act as an inspiration and a prototype for a neophyte like me.

Thanks in advanced! :)

Posted on Jun 11 '18 by:

sranvir profile

Ranvir Singh

@sranvir

Gamer. System Administrator. Physics enthusiast. Occasional writer. Pays attention to details; jsut not the necessary ones.

Discussion

markdown guide
 
 

Documentation should definitely unpack the architecture of the system as much as possible. Diagrams are useful for this.

A thorough description of the out-of-the-box behaviour is a basic requirement. If you are documenting a framework I would include examples on overriding or extending default behaviour. If I want to change behaviour X where do I put code Y? What patterns do I use?
I am a Java dev myself so I don't know to what extent this applies to a JavaScript framework, but for me the Spring Project is one of the best documented frameworks out there.

 

Yes, you are right about the architecture part. Often that's the thing I try to look for in any project that I am trying to incorporate. Half the battle is won once the user knows what goes where.

 

While I'm unsure of your project framework but if you already have a Git repository for it, then you could look into creating your documentation using reStructuredText and Sphinx to auto-generate all the static content (HTML, CSS, JS etc)

You can then deploy it via ReadTheDocs which handles building your documentation (via Git web-hook) and hosts it on a publicly accessible URL of your choice.

While it does have a bit of a learning curve but once you get the hang of it, all you'd need to create documentation is a Text Editor and Git commits :)

If you need an example, you can browse the one made by LetsEncrypt

 

Props to you for picking up a documentation project! I originally wrote a comment got uncontrollably long, so I put it in its own post:

I think you can do a lot with just markdown on GitHub, and it's easy to convert the Markdown into HTML if you decide you want to put it on its own website.

The best place to start contributing to documentation of a project that is new to you is usually by smoothing out the "getting started" section and writing guides that would help other beginners build some simple applications using the framework. I'd suggest you try doing a small project using the framework and take careful notes at every step about what you're doing so that somebody else could follow along by just copy-pasting. You can easily turn this into a guide for new users.

Most people coming to a framework are total beginners in it, so writing for other beginners from a beginner's perspective is immensely valuable. People with more experience in the project may actually have trouble seeing from a beginner's perspective so they usually really appreciate this type of contribution.

Good luck with your project, and please update us on your documentation journey!

 

Hi, Eli! I am coming back from your original post. It was as informative as it was inspiring. I am not sure if I would be using anything but vanilla markdown. In all honesty, I would prefer using just that, at least for the first couple of such projects.

Given all the learning curves involved with the core project and the act of documenting it, I doubt if there would be any room left for learning documentation tools. So it was a sigh of relief when you suggested it's okay to do that.

I will make a detailed post about the documentation project and how it goes. (A documentation about documentation. How meta!). Would love to hear your constructive criticism on that!

 

I look forward to reading about it! There are so many documentation tools, but the content is the most important part anyway. I love the simplicity of Markdown.

 

Is the framework open source and are you able to share some of the existing documentation?

 

Not sure... I have not started yet. But in all likelihood, the docs are going to be made public regardless of the source code.

 

UML class diagrams and flow charts.

 

excellent examples and a detailed plan.