How do you documenting your projects?

#discuss #documentation

Hi.

Documentation one of the important thing in software projects. But most of the developers are not likes documenting their projects.

If you're documenting your projects or only your codes, how do you do that?

Top comments (7)

Cécile Lebleu • Oct 18 '19

For some projects (not all, I admit, actually I've only used this method in... 3 or 4 projects lol) I like to take a journaling approach. Not exactly documentation for everyone else or for a client, but for myself.

When the project first starts, I create a markdown document and write an outline of what the project is all about. Sometimes I write an "App Store intro", describing in a sales-focused way what the project or app does and why it's easier to do it with this app than with the competition. Or a similar, fitting approach, for a website or anything else. Then, a list of the main features and most important aspects. Sometimes an estimated outline or even timeline of how I should embark the making of the project.

Then, during the actual building of the thing, for a few minutes after I've done a chunk of work—for example, before lunch, and in the evening when I'm done with my day, or even just at the end of a day, I will open up the document and write down the date, a list of what I've made, something needs to be done, how a specific thing works, etc. I also write my thoughts on it: "This process was particularly difficult and I had to learn how to do X and Y."

This helps with a few things:

I can easily roll back to the beginning and remember what the main goals of the project are. Sometimes it's easy to get lost in a teensy feature that doesn't really add the value that made us start the project in the first place.
I can roll back and know when I did something, why I did it this way, and how long it took.
I can look back at the end of the project and know what was easiest and fastest, what was most difficult and time-consuming. Studying this allows me to...
Provide better estimates to clients and co-workers; in time, cost, difficulty, stack, so on.
I can see how much I improve from one project to the next, or from the beginning to the end of a project.
And finally, it's a great starting point for an actual public documentation. Again, you have the "sales pitch", main features, how specific things work and why, and the reasons behind your reasoning three weeks ago, which isn't always easy to remember!

Casey Brooks • Oct 18 '19

I use Orchid to generate websites for all my documentation. I've been building it for a couple years now to be exactly the tool I need for documentation; blogs, wikis, changelogs, Javadocs, and much more, all well-integrated in one place. It also deploys directly to Github Pages for me too! No more juggling multiple tools, struggling to get them to work well with each other, and ending up with a non-cohesive experience for writing and reading docs!

Daniel P 🇨🇦 • Oct 18 '19

Depends on the project.

For server-side, I rely as much as I can on generated documentation. For front-end, I document functions and types. In both cases (but more-so for front end) I write README.md and as-needed other markdown files.

If you're working on server-side APIs, I believe it is imperative that you use either good self-documenting (like swagger generators) or even something like protobuf definitions, which can generate swagger documentation and the server boilerplate. The problem with writing it all yourself is that it's very easy to have server API and documentation not match. The README docs in this case would be specific to install, and dependency configurations.

lineldcosta • Oct 19 '19

Obviously swagger the best and easiest tool to integrate & with lot of community support available. Just checkout. & still if you find difficult let us know your code stack, will update some gist for you.