Scrivener07 commented 5 years ago

The Documentation

~45% done?

This issue is so I can track wiki related tasks.

Who are these documents for?

Authors new to scripting or programming in general.
Authors who are new to VS Code and excited to try a modern text editor.
Author who are firmly stuck to other editors for modding purposes.

How do these documents help me?

These documents explain how to use the extension and its features in great detail.
These documents provide information about the Papyrus scripting language in great detail.
These documents explain how to code with Papyrus in some detail.
These documents explain how to use the Creation Kit briefly.

What questions should I ask myself while writing documents?

Can I find what Im looking for at a glance?
What is my favorite part so far and what part do I find the most lacking?

Emphasis

The documentation should be thorough, but also accessible at a glance.
Do not assume the user to be fully knowledge on every subject. Provide plenty of supporting documentation to the topics here.

What does the end result look like?

Below I will try to create a sort of wiki site map which tracks the completion of pages.

Goals

[ ] Offline Compatible: All external links should be routed through the Glossary. The exceptions are links to CreationKit.com, code.visualstudio.com, or where justified on a case-by-case basis. These two external links are prefixed with the link destination when used. For example CK - Weapon or VS Code Keybindings.
[ ] Content Polish: Wax on, wax off.
- [ ] Feature Introduction Videos
- - [ ] Introduction to The Papyrus Language Extension
- - [ ] Introduction To Coding
- - [ ] Introduction To Debugging
- [ ] A very descriptive screenshot or two for every notable extension feature.
- Lean towards still screenshots within documentation.
- Save animated gifs for overview pages or very complex features.

Extension

Features

- [ ] Language Definition
- [ ] Static Analysis
- [ ] Smart Completion
- [ ] Refactoring
- [ ] Compilation
- [ ] Debugging
- - [ ] A page explaining the concepts behind debugging such as breakpoints and stepping.
- - [ ] A page on using the in game developer console.

Programming Section

Add some pages (not exhaustive) about programming with papyrus.

Add content for an introduction to setting up new projects and scripting environments.
Add content about script instantiation and object binding within the Creation Kit.
Add content for an introduction to scripting (briefly).
Add content for an introduction to arrays, and (briefly) for some advanced stuff.
Add content for an introduction to events, and (briefly) for some advanced stuff.
Add content for an introduction to inheritance, and (briefly) for some advanced stuff.
- [ ] Interoperation between Papyrus and Adobe Actionscript.
- [ ] Exposing Papyrus Properties to the Condition System.
- [ ] Hooking the Condition System with Papyrus events.

Language Section:

A complete onsite markdown conversion of the core Papyrus language documentation.

Why?

The creation kit websites are extremely painful to edit or even view and navigate.
The creation kit website information is overly fragmented across too many pages, with poor navigation.
I will be able to consolidate the differences between compiler versions (skyrim, fallout).
I will be able to greatly improve the quality of feature pages by using the onsite pages as supporting documentation.
The markdown wiki looks slick and has a better syntax.
Anyone can now clone a complete local copy of the Papyrus language reference all rendered in beautiful Markdown.

TODO

Continue to focus on feature related content now.
Project Panels: Visualizes which projects are in context and where.
Notes on how to get logs and extension output.
Document remote event completions.
How to uninstall the extension and xSE plugin?
Add more links to relevant VSCode docs for "further reading".
This is pretty much an Organization now. List all the sub-project repositories and dependencies.
Finish documentation for snippets. Improve snippets themselves too.
Note the ba2 archives have some naming conventions that unlock additional runtime behavior. For example: The Beta script flag and archive naming conventions.
Add citations to the creation kit wiki for everything in the language reference. Good thing I have a complete list of links for every page anchor within the onsite language reference. I plan to copy these links to the bottom of each language reference page as one list.
Corrections
Fix red links in papyrus reference. Switch these to page anchors.
Change the operator reference wording. Like I've stated that the operator inverts if the expression is on the right, not that the expression is inverted if the operator is on the left. The wording states it from the operator's point of view, if that makes sense? Rewrite the description without an "aside" mid-sentence.
The Bethesda documentation is worded with lots of asides (You know, nested sentences in English, its terrible) and other forms of distracting writing. This should be written with a more technical style.
Change text with a "speaker" and "audience" to have a more matter-of-fact style. By that I mean uses of "I", "me", "we", "us", and "you". This should be written with a more technical style.
The language reference is very fallout leaning right now and Im planning on making another pass on it to account for compatibility. Stuff like reworking the Language Keywords to show which compiler each is compatible with.
Search for all text containing the phrases "above" and "below" to ensure the topics remain cohesive and match the indicated location of other texts. There is no known occurrence of this issue within the current documents. This is my paranoia.
Fix INI settings on the Settings page.
Remove double-bullets on the side navigation. Use indentation instead.
Give all existing pages another round of editing for style consistency.
I should go through and make sure that all of our language for features matches VSCode.

Scrivener07 commented 5 years ago

Fixed

There is also a duplicate of the namespace section at the bottom of https://github.com/joelday/papyrus-lang/wiki/Papyrus

Scrivener07 commented 5 years ago

I should reevaluate the naming of the top level features. We want these features to match the user facing naming provided by VS Code. For example "Smart Completion" could be named "Intellisense".

I should go through and make sure that all of our language for features matches VSCode.

Scrivener07 commented 5 years ago

We should use Linting to mean code style analytics. I think whatever we actually do with linting in the future should be in the scope of fireundubh's stuff, with his standards as the defaults.

Scrivener07 commented 5 years ago

Im drafting some stuff about what kinds of general project structures are supported. I can go on to explain how a totally vanilla project is configured out of the box, to creating your own "import". Something like this in the docs with mock directory examples. If I can define a handful of popular/conventional ones it would be easy for users to point at one and say "yup, Im doing the # 3 setup".

For example in a totally vanilla setup these are the files in play.

...\Fallout 4
|   CreationKit.ini
|
\---Data
    |   Fallout4.esm
    |
    \---Scripts
        \---Source
            +---Base
            |       Institute_Papyrus_Flags.flg
            |       *.psc
            |
            \---User
                    Readme.txt

@Deadmano had a good point here too. Ill quote..

Problem is, who works in the base game? You should always have a clean working environment, no? It's so easy to miss an overwrite, especially if you are dealing with meshes/textures etc. That's why it has become the norm to use a VFS or at least symbolic links to bring in your outside assets but keep the base game clean. That way, when you're working on different projects, you can enable/disable them at will and not worry about breaking anything or having random leftover files you forget to remove. I surely can't be the only one who avoids directly editing the base game files? I would have thought that is a modding best practice? Same as we avoid mutation of variables and objects.

Scrivener07 commented 5 years ago

Some saved notes for helping users. This has potential to become a useful tool in the project meta documents (issue templates, etc).

Interacting with Users

Here are some ready to use solutions for helping users.

Viewing Files & Directories

If you don't mind me taking a look at your directory folder, I may be able to assist further.

Do not execute the file until its been placed in the intended directory.
Place the CreateDirectoryTree.bat file inside the directory and double click to run.
This will create a new file in the same directory called DirectoryTree.txt.

Alternatively, if you know what your doing you can use tree on the command line.

tree /f /a > ".\DirectoryTree.txt"

Download

CreateDirectoryTree.bat.zip

Scrivener07 commented 5 years ago

Create a standard procedure for testing new release versions.

Scrivener07 commented 5 years ago

Add citations to the creation kit wiki for everything in the language reference. Good thing I have a complete list of links for every page anchor within the onsite language reference. I plan to copy these links to the bottom of each language reference page as one list. For example..

joelday / papyrus-lang

Documentation for this extension, VS Code, and Papyrus #60

The Documentation

Who are these documents for?

How do these documents help me?

What questions should I ask myself while writing documents?

Emphasis

What does the end result look like?

Goals

Extension

Features

Programming Section

Language Section:

Why?

TODO

Corrections

Interacting with Users

Viewing Files & Directories

Download

See Also