search

nasa / fprime

F´ - A flight software and embedded systems framework
https://fprime.jpl.nasa.gov
Apache License 2.0
10.02k stars 1.29k forks source link

Reorganize docs with Diataxis method #2597

Closed thomas-bc closed 1 month ago

thomas-bc commented 5 months ago

Description

See https://diataxis.fr/

Now that we have a HowTo Guide section, I think it would be really great for navigation and understandability if we reorganized our documentation this way. 4 categories:

I've seen this method pop up more and more and I think it's really great.

thomas-bc commented 5 months ago

Realistically, this could simply be taking the API section out of the User Guide and into a new Reference section in the sidebar/TOC, and grouping Design and Philosophy section in a top level section of the User Guide.

Maybe also double check that things in the User Guide don't belong to another (HowTo or Reference) section.

GavinKnudsen commented 5 months ago

Would it be alright if I take a crack at this? It would be my first issue in this project. Thanks!

thomas-bc commented 5 months ago

Yes please that would be great! Let me know if you have any questions or need anything

GavinKnudsen commented 5 months ago

@thomas-bc Thanks. I have done some looking around the current documentation and had a question. Would it make sense to move the "getting started with F'" content under the "Getting Started" section? My my thought process is we can have the four categories that you mentioned, but also have a kind of "Start here" section that includes how to read the documentation, the basics of F', and/or how to get started all consolidated into one section where it is easy for new learners to know where and how to start. Should this section be included in the 4 categories as well? What are your thoughts?

thomas-bc commented 5 months ago

Yes I think that would make sense! Feel free to clean that section up as well since one of the link is the landing page and another one is the tutorials which are already referenced in the sidebar. Also maybe move the Console autocomplete thing under the GDS part of the User Guide as this isn't really relevant to "get started"

thomas-bc commented 5 months ago

Also this link here https://github.com/nasa/fprime/blob/b89b5d91c4250182a71948aeac57b21744a1e119/docs/_includes/toc.md?plain=1#L103

should be changed to link to /fprime/HowTo/general.html instead

Saty70 commented 4 months ago

hey i want to contribute on this issue can you guide me what should be prequisite needed to know to do so as i am new to open source contribution

GavinKnudsen commented 3 months ago

Sorry I've been inactive for a while and thank you for your patience! I've been busy with school, but now that my semester has ended, I have more time to work on this project. I'm aiming to submit a pull request by Monday evening, assuming there are no unforeseen issues.

@Saty70, for the prerequisites for this issue, you should be familiar with markup languages such as HTML and review the diataxis documentation method. Additionally, I recommend checking the project's contributing guidelines and documentation to help you get started.

This is my first contribution to this project as well, and I am not a maintainer, but I would still be happy to guide you if you have any questions. If you decide to work on a different issue, please feel free to explore the easy first issues list.

Thank you for understanding, and let me know if you have any questions.

Saty70 commented 3 months ago

Thanks @GavinKnudsen for guiding really helpful