Documentation improvement planning

Hi together,

i open this issue to plan, discuss, collect things for an improvement of the documentation.

I‘m using an issue because it‘s better for discussion etc.

First of all i collect old issues regarding documentation (please comment if there‘re any missing that are currently not documented in the wiki:

• https://github.com/Marus/cortex-debug/issues/558#issuecomment-1004173498 -> Add hint for ,x etc
• #553& #188 -> Add hint on how to debug single core in multi core system
• #550 -> Add example to description in Wiki and maybe add FAQ entry? Or only FAQ?
• #549 -> SWO example
• #515
• #511 -> State dependencies like libncurses somewhere; Maybe also a good example on hoe to deal with WSL for now?
• #510 -> State somewhere in the “theory of operations” what to do when user wants to setup GDBServer by himself
• #461 -> Not sure anymore if we should state something about that as it is very special. Maybe mention that using override commands is needed when using external server type operation
• #442 -> Describe attach and launch
• #400 -> FAQ (mention the words SRAM / ITCM RAM)
• #366 -> runToMain / runToEntryPoint are working after reset/restart now. At least in prerelease 1.1.1 => We just need to document that setting the temporary breakpoint can fail
• #352 -> add FAQ entry with J-Link Remote Server for that
• #332 -> Document how to use them -> link to VSCode documentation
• #323 -> add small entry on how to use different commands from command palette (maybe others too)
• #283 -> FAQ How to add multiple graphs (from different ITMChannel/ports)?
• #277 -> check old webpage content and look for any valuable description and example launch configuration
• #220 -> Has some good description on pitfalls/issues user can have with setting up SWO
• #200 -> debuggerArgs example in the wiki for using a .gdbinit file with a hint to not use continue in it
• #192 + #115 -> Check if behaviour is already described enough in wiki
• #173 + #551 => example on how to use gdb console to read and write registers / REPL hint and link is a valuable info; registers moved to variables section in next release
• #139 => graphing is documented enough in wiki. So only last (some kind of offtopic) comment is relevant which are two feature request. Create two new issues for that?
• #111 => State somewhere how to handle different os paths and give a hint that launch.json is much more flexible
• #105 => add FAQ entry for: Failed to get Stack Trace: Invalid thread id
• #104 => try to get an example (more easily to start) from somewhere. How is the javascript module supplied/imported? Additional extension?
• #76 => stated enough in wiki? Maybe add to installation guide
• #59 => FAQ entry
• #55 => Something to mention as every new user is confused about that
• #36 => add some hint from here for hoe to use external server type
• #12 & #727 => see if all feature work with a Rust example and document it (e.g. the debug info enabling needed which is mentioned in both tickets)
• #1 => Maybe state current situation (no money) in What’s new page and Wiki/README

I‘m also haveing thoughts about following things:

• Add a “theory of operation” section with some diagrams
• “teach” users to use intelliSense
• Use debug_attributes.md as much as possible so we don‘t need to document things twice.
• extend IntelliSense examples (maybe some with RTT/SWO output/graphing)
• Change Link for prebuild OpenOCD binaries to https://github.com/xpack-dev-tools/openocd-xpack/releases/ (at least for Linux and MacOS)
• Restructure wiki -> we have a lot of common settings and we most likely only need special hints on single parameters (sets) and maybe some special examples (others should be part of IntelliSense)
• Cleanup issues and mark open ones with labels, so users and contributers can more easily search trough them
• Move OpenOCD build manual to a seperate wiki page
• Add a what‘s new page to better inform users about changes e.g. https://github.com/alefragnani/vscode-whats-new
• Update screenshot in README.md
• Add animated gifs to documentation (e.g. created with https://www.screentogif.com/ + enableing screencast mode in VSCode) for things like command pallet
• Remove stale/unused branches => at least rtosSupport, serialport-v12.4.0, fix-webpacked-binary-module, fix-webpack-2, mp

That should be my first thoughts. Maybe not complete but i will update this post when working on the documentation.

Happy to receive any feedback or input 😄

Best regards Philipp

[haneefdm]

@PhilippHaefele Thanks again for all your help. I never imagined seeing such low numbers for open issues. There is now a new topic and I hope people will like it. I will push it out to a preview release soon.

https://github.com/Marus/cortex-debug/wiki/Disassembly-Debugging

Can’t go in reverse – from disassembly to source – and you are supposed to be able to. Not sure why it is not working. People probably don’t even know you can do that.

The UI is still pretty rough – you will find out as you use it more and more. Sometimes, all of a sudden you get a second disassembly view. But moving through the stack frame and seeing the registers and the disassembly and source all getting updated was cool (for me at least).

[haneefdm]

@PhilippHaefele FYI: I started a new page as I am implementing the feature. So, things are in flux.

https://github.com/Marus/cortex-debug/wiki/Multi-core-debugging