Immediate-Mode-UI / Immediate-Mode-UI/Nuklear

Move documentation inline with Doxygen

Open
#394 7 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

High Priority
Dominant language
C
Stars
11.4k
Forks
686
Avg merge
4d 1h
Merged PRs (30d)
3

Description

I've noticed that documentation is somewhat lacking. Stuff is hard to find, splintered around or simply not documented. I also notice (from other issues) that more people acknowledge this and are willing and working on it, which is nice! I have the following proposal(s):

1. Remove https://immediate-mode-ui.github.io/Nuklear/doc/index.html
2. move all documentation effor to github wiki
3. improve documentation needed for beginners
* A take me by the hand 'Getting Started' page
* quick links to 'Examples' and 'Demo's' and 'Component documentation'
4. document ALL components.
* many components arent even in the component list yet. You have to scavenge through code to find out whats available.

This is motivated by a couple of reasons:
1. https://immediate-mode-ui.github.io/Nuklear/doc/index.html is somewhat unfriendly to use and seems lacking, not up to date. If i were new and wanted to get started i would click on the "Documentation" button on the readme page and be greeted first some paragraphs of text and then something that looks like full on api documentation (flags, constants, dependencies). I have to really try to find some getting started information. The site itself also doesn't look that inviting.
2. Removing https://immediate-mode-ui.github.io/Nuklear/doc/index.html and switching everything to github centralizes all documentation efforts. Everyone will know where to look, theres only one place. If its not here, it doesnt exist. This ofcourse improves the maintainability aswel.
3. Many open-source projects switched to full github wiki so the target audience should be familliar with the UI and how to use it, removing even more barriers 💯

Ofcourse i'll be willing to put an effort in this. but first, i'm wondering what your thoughts and idea's on this are.

-Robert

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the README's Documentation link and the current Doxygen site at immediate-mode-ui.github.io/Nuklear/doc/index.html, then compare them with the GitHub wiki. Define a scoped documentation plan covering a Getting Started page, links to examples and demos, and the component list. Done should mean the agreed documentation home is current and beginner guidance and component coverage are complete.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.