Documentation re-org 2018: Difference between revisions
Jump to navigation
Jump to search
m (testing list) |
m (fixed list) |
||
| Line 8: | Line 8: | ||
Problems: | Problems: | ||
# When you go to https://gnuradio.org/doc/doxygen/ the organization may be confusing for new people, and several of the drop downs don't have useful info. The wiki home page attempts to provide guidance. | |||
# We don't define what type of information goes where. E.g., if someone new-ish wants to get more info about something (e.g. PMTs), it's not clear whether to use the wiki or usage manual. | |||
# Some information is duplicated across the wiki and usage manual (e.g. the wiki's BlocksCodingGuide is like a condensed version of several usage manaul sections). | |||
Proposed Solution: | Proposed Solution: | ||
# One by one, migrate the information in the usage manual sections and components sections to the wiki, removing any redundancies in | |||
the process. On the home page of the wiki, we will link to pages in the wiki instead of pages in the Doxygen usage manual | the process. On the home page of the wiki, we will link to pages in the wiki instead of pages in the Doxygen usage manual | ||
# We can make the doxygen usage manual redirect to the wiki, so people use to using it (or who have bookmarked it) will not be disturbed | |||
# Rename "GNU Radio Manual and C++ API Reference" to "GNU Radio C++ API Reference" and try to remove links to the old usage manual | |||
# The wiki itself needs a re-org, or at least a minor clean up. Perhaps categorize pages into documentation/tutorials/news/events/archives | |||
# Figure out how new people registering for the wiki can actually be granted access quickly. One idea- add a field to the registration process asking for a quick blurb about how they use GNU Radio, and when someone registers it should email someone who can quickly see that it's not a bot, and verify the registration. | |||
Revision as of 00:26, 10 May 2018
Currently, GNU Radio documentation lives in one of the following places:
- Usage Manual in Doxygen (18 pages that cover various topics across GR)
- "Components" descriptions in Doxygen (various length blurbs about each category of GNU Radio blocks)
- Doxygen strings for each block, describing arguments and such (this info lives in the same files as the code for the block)
- Wiki
Problems:
- When you go to https://gnuradio.org/doc/doxygen/ the organization may be confusing for new people, and several of the drop downs don't have useful info. The wiki home page attempts to provide guidance.
- We don't define what type of information goes where. E.g., if someone new-ish wants to get more info about something (e.g. PMTs), it's not clear whether to use the wiki or usage manual.
- Some information is duplicated across the wiki and usage manual (e.g. the wiki's BlocksCodingGuide is like a condensed version of several usage manaul sections).
Proposed Solution:
- One by one, migrate the information in the usage manual sections and components sections to the wiki, removing any redundancies in
the process. On the home page of the wiki, we will link to pages in the wiki instead of pages in the Doxygen usage manual
- We can make the doxygen usage manual redirect to the wiki, so people use to using it (or who have bookmarked it) will not be disturbed
- Rename "GNU Radio Manual and C++ API Reference" to "GNU Radio C++ API Reference" and try to remove links to the old usage manual
- The wiki itself needs a re-org, or at least a minor clean up. Perhaps categorize pages into documentation/tutorials/news/events/archives
- Figure out how new people registering for the wiki can actually be granted access quickly. One idea- add a field to the registration process asking for a quick blurb about how they use GNU Radio, and when someone registers it should email someone who can quickly see that it's not a bot, and verify the registration.