# The pitfalls of documenting a project
**URL:** https://fortran-lang.discourse.group/t/the-pitfalls-of-documenting-a-project/1773
**Category:** Tutorials
**Created:** [August 31, 2021, 1:59pm UTC](https://fortran-lang.discourse.group/t/the-pitfalls-of-documenting-a-project/1773 "2021-08-31T13:59:42Z")
**Posts on this page:** 4
**Page:** 1
### Author:  [@vmagnin](https://fortran-lang.discourse.group/u/vmagnin)
#### Post date: [August 31, 2021, 1:59pm UTC](https://fortran-lang.discourse.group/t/the-pitfalls-of-documenting-a-project/1773/1 "2021-08-31T13:59:43Z")
You may be interested by the conference given by Emmanuele Bassi at the _GNOME Users And Developers European Conference_ (GUADEC) this summer:
_[If you write it they will come, or lies free and open source developers tell themselves about documentation](https://events.gnome.org/event/9/contributions/192/)_
You can watch that conference here:
[https://www.youtube.com/watch?v=0preyzEb-fY&t=4120s](https://www.youtube.com/watch?v=0preyzEb-fY&t=4120s)
or read the text in that Markdown file:
[https://events.gnome.org/event/9/contributions/192/attachments/41/109/documentation.md](https://events.gnome.org/event/9/contributions/192/attachments/41/109/documentation.md)
Emmanuele Bassi is a developer of the GTK project, whose answers on the [GNOME Discourse](https://discourse.gnome.org/c/platform/5) are always very helpful, with very clear arguments.
* * *
The documentation problem is of course not specific to Fortran, but is important for the success of a project, open source or not. The Fortran community can use this post to discuss about it. Share here your opinions and experiences about documenting your projects.
---
### Author:  [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)
#### Post date: [August 31, 2021, 10:47pm UTC](https://fortran-lang.discourse.group/t/the-pitfalls-of-documenting-a-project/1773/2 "2021-08-31T22:47:13Z")
Uh, fully agree developer documentation is really hard to get right. I guess many of my projects are lacking a lot on this side. For most of them I’m not really sorry for haven’t invested time there, but for some I would really like to have a straight-forward way for a new developer to on-board, without requiring them to learn all things the hard way.
I can see that a contributing guideline, style recommendation and design rationale document might be a first step, but beyond that I’m not sure what is needed as a kind of knowledge base to make a project sustainable.
I’d be interested to learn and explore ways on how to improve here. Maybe projects like fpm and stdlib, as larger collaborative projects, are a good sandbox for trying out different ideas of building a developer knowledge base?
---
### Author:  [@vmagnin](https://fortran-lang.discourse.group/u/vmagnin)
#### Post date: [September 1, 2021, 7:35am UTC](https://fortran-lang.discourse.group/t/the-pitfalls-of-documenting-a-project/1773/3 "2021-09-01T07:35:31Z")
The post [User-facing documentation · Issue #182 · fortran-lang/stdlib · GitHub](https://github.com/fortran-lang/stdlib/issues/182) was very inspiring for me: I discovered [The Grand Unified Theory of Documentation](https://documentation.divio.com/). I slowly try to apply it to gtk-fortran.
The introduction of that site says:
> There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called _documentation_ , there are four.
> They are: _tutorials_ , _how-to guides_ , _technical reference_ and _explanation_ . They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.
---
### Author:  [@vmagnin](https://fortran-lang.discourse.group/u/vmagnin)
#### Post date: [May 5, 2022, 8:49am UTC](https://fortran-lang.discourse.group/t/the-pitfalls-of-documenting-a-project/1773/4 "2022-05-05T08:49:20Z")
As you may know, the [fpm doc](https://fpm.fortran-lang.org/) and [stdlib doc](https://awvwgk.github.io/stdlib-docs/) use the [Diátaxis](https://diataxis.fr/) method developed by [Daniele Procida](https://twitter.com/evildmp). He has worked as a Django developer and is now working at Canonical (Ubuntu) to evolve its documentation.
In this inspiring _Write the Docs 2021_ conference, entitled “Always complete, never finished”, he explains how to use efficiently Diátaxis to document your new project or to restructure an existing documentation:
[ ](https://www.youtube.com/watch?v=Wc7n7uIg4AM)
The process is also explained in that page:
[https://diataxis.fr/how-to-use-diataxis/](https://diataxis.fr/how-to-use-diataxis/)
If you wonder what means Diátaxis, Wikipedia says:
> In [Eastern Orthodoxy](https://en.wikipedia.org/wiki/Eastern_Orthodoxy), a **diataxis** (διάταξις, ‘order’; plural _diataxeis_ ) is a guidebook for the service of the [Divine Liturgy](https://en.wikipedia.org/wiki/Divine_Liturgy).