Flesh out documentation

[joshuacc]

While there are several open documentation issues already, this issue is for discussion of documentation improvements as a whole.

Docs that we have:

• Minimal help at the command line
• The README
• ahkpm.dev, which is basically a nicer looking rehash of the README
  • The repo for the site: https://github.com/joshuacc/ahkpm.dev

Questions to answer:

• What are the biggest shortcomings in ahkpm's documentation?
• How specifically do we address them?
• Will doing piecemeal improvements get us to where we want to go? Or do we need to be more deliberate in planning out the documentation?

@hwayne, I'd be especially interested in your input.

[joshuacc]

I think most of the potential audience for ahkpm can be described along two axes.

1. Familiarity with AutoHotkey itself: from (a) newbie to (b) old hand
2. Familiarity with programming language package managers, from (a) newbie to (b) professional software engineer

As of right now, ahkpm's docs probably shouldn't try to address the intersection of 1a and 2a (total newbie).

In my mind the primary audiences are:

• The intersection of 1a and 2b (software engineers new to AutoHotkey)
• The intersection of 1b and 2a (existing AutoHotkey users who are unfamiliar with package managers)

For simplicity I'll refer to them as engineers and power users, respectively.

Needs of engineers

• How is this similar to and different from package managers I'm familiar with?
• Can I host packages somewhere other than GitHub?
• What is the exact format of the ahkpm files?
• How does the dependency resolution algorithm work?
• How do I publish and maintain a package?

Needs of power users

• What the heck is a package manager?
• How do I use it?
• Seriously, is there a tutorial I can walk through?
• How do I fix things if something goes wrong?
• What is GitHub?
• What is Git?
• What is the relationship between a git repo and a package?
• What are these ahkpm files for?
• How do I publish and maintain a package?
• What is semantic versioning?
• What are version ranges/constraints?

[joshuacc]

Here's a possible documentation outline that accounts for most of the things mentioned above.

• Introduction
• Commands
  • All the commands...
• Guides
  • How to install and use a package
  • How to publish a package
• Concepts
  • What is a package manager?
  • Git
  • GitHub, etc
  • Semantic versions
  • Version ranges
  • ahkpm's files
• Advanced
  • The dependency resolution algorithm