Advice on tools for forum posting?

[610yesnolovely]

I recently posted my first mod announcement to the forums, the forum editor is okay for general chit-chat, but it's a PITA for mod announcement readme. I do not wish to ever waste three hours of my time wondering trying to format a large document by hand, wondering why it forgets half of my edits. Not. Fun.

I noticed a lot of well formatted, image laden mod announcements - from what I've read the easiest way to do this, especially with GitHub, is write markdown and display it in a browser on GitHub, then once you're good just copy and paste that. Usage of pandoc (which I'm aware of) may be useful.

Any seasoned modders advice?

A good example I found was @zer0Kerbal's - the GitHub readme.md is quite marvellous.

 

[zer0Kerbal]

On 2/4/2022 at 2:51 PM, 610yesnolovely said:

GitHub readme.md is quite marvellous

thank you @610yesnolovely. +1

Good question: Usually I get the feeling that mod / add-on documentation is an after thought, a chore. It shouldn't be.

Some suggestions (you probably know all this):

• Ask questions and learn from others (as you are doing here); learn, adapt, improvise, improve - (Kerbal Kaizen approach) and develop your individual style
• Approach documentation as a player - what do I want to see?  Think journalism and the W?W?W?W?W?H? (W5H?)
• Kindly remember that English often isn't a native language to most Kerbal Space Program players... hence my strong focus on localization
• Documentation is marketing. Suggest not taking it too serious - but... it is your Brand
• no pics, no clicks....
• remember the kerbal sense of humor 
• Take an iterative approach - which simple means update the behind-the-scene gears every version of every mod.
• With the iterative approach, use a semantic numbering system in the file name of the template, and include the file version in the templates.
  • A.B.C.D or A.B.C (aka #.#.#.# or #.#.#) is an example.
  • standardize what each number means (major.minor.patch.build or major.minor.patch)
  • write this down - I do here: 
  • for me: 
    • build (least significant digit): inconsequential changes like typos, and other minor things - changes to documentation, url, etc.
    • patch: slight changes that don't (normally) affect saves but more than just a minor
    • minor:  standard version updates (like the one you posted about)
    • major: (most significant digit): game changing changes - like a new owner
    • I reserve several key version for things x.9.9.9 or x.x.9.99 are pre-releases or adoptions, x.9.9.x or x.x.9.x are for betas and prereleases
• If you have more than one mod (or even if just one) - use a template; even if it just is a copy in another directory of all your template files. Just see the raw version of one of my readme.md files (or even the .htm version)
  • Examples of template files:
  • release.bat
  • deploy.bat 
  • readme.md (readme-v1.0.0.0.md)
    • the latest version of my readme.md template is v1.6.6.0 - which I should be working on right now 
• Standardize your GitHub or GitLab repos - as much as you can. Should feel like the same repo for every repo - at least for the behind the scenes.
• now to the liquid fuel and oxidizer of the suggestions:
• My workflow is to build the mod's readme -
  • upload the readme.md to GitHub to use as it's readme
  • use pandoc (or Typhora/MM/MDE to save as htm (there is also several automatic markdown --> html workflow actions now available on GitHub)
    • open the readme.htm in browser and copy it to a forum post
    • I now only include the .htm version of readme (and soon release notes) in the release.archive
  • SpaceDock uses markdown for its information page - so just use the readme.md
    • caveat is for releases - best to use plaintext for the release notes initially, then you can change to markdown version
    • reason is that the email sent to subscribers looks horrible with markdown or htm so use plaintext (or simple markdown)
    • then if you so desire change to htm or markdown
  • CurseForge uses either wysiwyg (htm) or markdown - to varied levels of success

 

• Tools:
  • shields.io
    • creates those wonderful images like: 
    • 
    •  
    • 
    • 
    • 
    • 
    • 
    •    
  • VS Code / VSCodium
    • has markdown lint and preview mode
  • Notepad Plus Plus / NoteTab Light / Atom
    • has markdown lint and preview mode (mostly works)
  • Typora / Markdown Monster / DA Markdown Edit / Online: https://stackedit.io/app#
    • live preview is a must.
    • Most will convert between multiple formats
    • Mostly I use Typhora (really cheap to buy) - but sometimes I have multiple versions open
    • often when working on a markdown file I will use Notepad++ or VS Code and have Typhora (or another) open so I can see the live preview.
  • pandoc.exe --> a universal document converter - more here.
    • use it batch and python automation to convert from .md to .htm;
    • can do markdown / html to wiki
    • its fast, and darn good. 
    • pandoc can generate full standalone pages, or just document fragments like what I use (but I prefer the fragments)
    • handles GitHub flavored markdown remarkably well
  • jq.exe --> jq is a lightweight and flexible command-line JSON processor - more here.
    • use it in batch automation files (like buildrelease.bat) to retrieve mod and KSP version from the mod.version file
    • then use that information to build shields.io etc.
    • shouldn't need it for python
  • OneCommander --> One Commander V3 is a modern file manager for Windows 10 and Windows 11. Features include tabs, dual-pane browsers, columns navigation, built-in preview, a theming system, color tags, and much more. It is free for home use and has no ads.
    • I cannot say enough praise for this utility - 

 

 

Maybe more later. 

 

Spoiler

 

PS - don't try to be perfect - that is the advantage of iterative work - heck, because of you I just found two minor issues with the readme you linked to - (some bracket graffiti!   )

Edited February 9, 2022 by zer0Kerbal
1.4.1.7

[610yesnolovely]

5 minutes ago, zer0Kerbal said:

thank you @610yesnolovely. +1

...

Maybe more later. 

Whoa... that's a whole heap, my brain will explode if you write more. Thanks! I'll have to re-read that when I'm more awake.

I knew some of those things, the more general development (I think most modders are software developers by day), but the particular tips about KSP, this forum, markdown, pandoc, shields.io - that's super useful. The forum editor really sucks, and after some forum searching I concluded that the best approach is to look at people's GitHub and try to guess how they did it.

For build automation @Nerteahas some here: https://github.com/post-kerbin-mining-corporation/build-deploy, and https://github.com/ihsoft/KSPDev_ReleaseBuilder by @IgorZ- plenty of good stuff out there. I'm a Linux, Emacs, make, python, automate-all-the-things old school (but not as old some ).

[zer0Kerbal]

28 minutes ago, 610yesnolovely said:

most modders are software developers by day

*chuckle* agree, most

[zer0Kerbal]

another

 

https://stackedit.io/app#