Jump to content

miked

Members
  • Posts

    32
  • Joined

  • Last visited

Reputation Activity

  1. Like
    miked reacted to zador.blood.stained in [420] - Build tools testing, for improvements and/or documentation   
    There are some options that control this behavior: first, FORCE_CHECKOUT=no should disable overwriting modified source files, second, DEBUG_MODE=yes (it's a really non-descriptive name for this option that should be changed) allows creating patches based on your modifications to the sources.
  2. Like
    miked got a reaction from David in [420] - Build tools testing, for improvements and/or documentation   
    Initial thoughts:

    - Why is root needed, and what will it do to my system? (Docs could give an overview of what it will install, etc). Is this why virtualbox etc. is recommended? (but not needed?) Is it conceivable to run as normal user, with a few sudo calls for anything needing root?

    - Why does it update code (and sunxi tools etc) every time it is run? It seems to be set up for automating regular builds, but I imagine users who are trying to patch or hack on their system might have to compile several times and wouldn't want to get code while making changes. (There is the ".ignore_changes" option but it is handled differently from the other options. If it was documented, and perhaps echo'd a message that code updating was being skipped, that might suffice).
     
    - Similarly, does it need to automatically clean everything? While experimenting with FEL mode, it takes many minutes compiling and prepping the image each time, even if no changes were made, and then unmounts the image when done, so it is difficult to continue experimenting outside of compile.sh.
  3. Like
    miked got a reaction from Igor in [420] - Build tools testing, for improvements and/or documentation   
    I'm currently trying out various features before going through the tools in detail and attempting to tackle all scenarios.
     
    I'll write down some thoughts in this thread for now.
  4. Like
    miked got a reaction from Tido in [392] - documentation rework   
    I've added a welcome message to the docs Home, to temporarily minimally address some UX issues.
     
    There are several use cases for the documentation:
     
    1. New users, who might easily give up and try something else unless they're walked through everything right from the start.
    - Getting Started should be prominent for them.
    - "What is the current state of Armbian?" might need to be answered in the docs, since outdated info about hardware acceleration, HDMI etc. can be found elsewhere and may deter these users (or maybe that should be left to the main armbian.com site)
     
    2. Users of all levels who have frequently asked questions.
    - Do people still look for FAQ sections? If so one should exist and be easily seen.
     
    3. People who've run into problems
    - FAQ and/or Troubleshooting should be easily found.
     
    4. Serious users who will actually read through the ToC and documentation
  5. Like
    miked got a reaction from Igor in [392] - documentation rework   
    I've added a welcome message to the docs Home, to temporarily minimally address some UX issues.
     
    There are several use cases for the documentation:
     
    1. New users, who might easily give up and try something else unless they're walked through everything right from the start.
    - Getting Started should be prominent for them.
    - "What is the current state of Armbian?" might need to be answered in the docs, since outdated info about hardware acceleration, HDMI etc. can be found elsewhere and may deter these users (or maybe that should be left to the main armbian.com site)
     
    2. Users of all levels who have frequently asked questions.
    - Do people still look for FAQ sections? If so one should exist and be easily seen.
     
    3. People who've run into problems
    - FAQ and/or Troubleshooting should be easily found.
     
    4. Serious users who will actually read through the ToC and documentation
  6. Like
    miked got a reaction from lanefu in [392] - documentation rework   
    I've added a welcome message to the docs Home, to temporarily minimally address some UX issues.
     
    There are several use cases for the documentation:
     
    1. New users, who might easily give up and try something else unless they're walked through everything right from the start.
    - Getting Started should be prominent for them.
    - "What is the current state of Armbian?" might need to be answered in the docs, since outdated info about hardware acceleration, HDMI etc. can be found elsewhere and may deter these users (or maybe that should be left to the main armbian.com site)
     
    2. Users of all levels who have frequently asked questions.
    - Do people still look for FAQ sections? If so one should exist and be easily seen.
     
    3. People who've run into problems
    - FAQ and/or Troubleshooting should be easily found.
     
    4. Serious users who will actually read through the ToC and documentation
  7. Like
    miked reacted to lanefu in [392] - documentation rework   
    I believe it polls the repo every few minutes and if there's a change it rebuilds.
  8. Like
    miked got a reaction from lanefu in [Documentation] software proposal for Armbian wiki   
    I'm not actively doing anything at the moment, to avoid stepping on toes.
    I would like to QA/edit the organization and navigation of the docs (within the current tools/layout). I could probably do that now?
    I might add to some of the content, for beginner readers, but only after others' rewrite tasks are done.
  9. Like
    miked got a reaction from Tido in [Documentation] software proposal for Armbian wiki   
    I feel that settling on filenames/URLs as quickly as possible should be a high priority. Are the current filenames settled? (including the "feel boot" typo?) If perfect permanent links are infeasible, breaking links and leaving temporary/WIP names for long periods should at least be avoided as much as we can. I don't know how much of a problem it could really be, but I imagine people googling a common question, and ending up at a permanent forum post somewhere that contains a broken link to the documentation.
     
     
     
    I was curious about collapsible navigation links and came across this mkdocs theme example: http://developer.helpmonks.com/
    Code and description can be found here: https://github.com/mkdocs/mkdocs/issues/588
    This appears to be a WIP, has bugs and might be hacky, and is extra complication on top of readthedocs, so I don't recommend we use it, just an idea.
    I downloaded the theme and tried it out on our docs. It doesn't display subsections in the navbar, which is a problem. It looks like their theme's toc.html removes it, and adds support for organizing .md files into subdirectories.
  10. Like
    miked got a reaction from Tido in [Documentation] software proposal for Armbian wiki   
    Looks like it's really coming along well!
     
    Do you want UX feedback discussed here, or on https://github.com/igorpecovnik/lib.docs(are issues disabled for it???), or should we wait until it's ready for feedback?
     
     
     
    For example... When I'm at docs Home, the User Guide sections are offscreen on my computer. Even if it is onscreen, it is below stuff like Task Tracking, Changelog etc. As a complete newb, if I go to the docs, I might skim the Home doc, maybe hit Next and stop reading by the FEX section at best. I might skim the sidebar topics... if I'm lucky I'll notice "Getting started" near the bottom. Otherwise I'll think that Home is all the getting started info there is and conclude that this all requires some expertise that I don't have.
     
    I don't know if such an issue is already being addressed with a doc reorganization, or if it is now baked into the current design.
  11. Like
    miked got a reaction from lanefu in [Documentation] software proposal for Armbian wiki   
    I continued my permanent link experiment, it is working locally. It's a simple bash script. I'm not 100% convinced it's a good idea. It is simply:
     
    1. A human adds markers in the source document where you want to specify an anchor name, overriding what is automatically generated.
    2. When html is built, script replaces the autogenerated anchors with the specified one, in mkdoc's output files (The anchor id, and links to it in the html files and search index).
     
     
    The marker that goes in source can be something that will not be displayed even if not properly processed out, eg:
    abuse a markdown reference: "[permalink]: my-anchor-name"
    or fake html that browsers will ignore: "<permalink="my-anchor-name">
    (the latter can be processed more cleanly).
     
    It can be used sparsely in the source, only where desired (but then a site maintainer must add the tags when the scripts warn of potential broken links), or it can be used all over (but then either the doc writers must deal with them or a site maintainer).
     
     
    Whether this is worth it is someone else's call, so i'll leave it until someone wants to move forward. Any decision on it should be easily changed later.
  12. Like
    miked got a reaction from wildcat_paris in [Documentation] software proposal for Armbian wiki   
    Here's the best I can come up with so far, that looks possible:
     
    Required: Permanent links, TOC, searchable  Desired: Minimal source structure, hard to break. Not important: Platform independence (documentation source need not work as-is with other software).     For permanent links, we have fixed file names, and anchor IDs embedded in the source. Something like: [permalink]: how-to-boot # How to boot? Insert SD card... We process the output of mkdocs so that where "permalink" was in the source, the next anchor is replaced with what we specified. The link source markdown could be generated by our scripts, then put in the source document. The writer then wouldn't need to create the link text. If it is missing it won't break anything.   The rules for editing docs, to avoid breaking links, are: - Do not change file names - Do not edit permalink line, or separate it from the section's text - Do not move a permalink'd section to another file   ([id] or [anchor] might be preferred over [permalink]. The tag could go after the title if preferred. I think this uses valid markdown syntax.)         Edit: These tags are optional, only necessary if we have external links to the documentation section, and if the section title is changed and no longer matches what was linked. If we wanted to avoid cluttering the source with these tags, we could have our scripts generate these lines only for any links that were in the previous mkdocs output but not the new one, indicating a possible change to the section title. These tags would essentially indicate the original section title. [permalink]: how-to-boot # Booting your device After ensuring your power supply...
  13. Like
    miked got a reaction from sysitos in Claim a task, set DUE date and start doing it!   
    Sorry if getting off topic, but... a relay does that. Search "arduino relay" on ebay (< $2) or amazon etc for the easiest solution. Cut the live wire of a power cord and put the relay module in between.
  14. Like
    miked got a reaction from Tido in [Documentation] software proposal for Armbian wiki   
    There are a few tasks mentioned in this thread:
    - Documentation html software and layout (mkdocs output, toc, search etc.)
    - Edit Armbian.com to integrate the new docs location. Also link to documentation pdf somewhere.
    - Auto generate and process the docs/pdf on github documentation commits (now do this on wiki edits?)
    - Tweak pdf generation to look like a professional book.
    - Reordering/structuring documentation so both newbs and experts can easily get to what they need (is this a separate task?)
    - General documentation rewriting and additions (these are separate tasks)
     
    As far as I know, all of these tasks are being worked on.
    I'm not currently working on any of them, let me know if I can help!

     
     
    I got confused about this too. But it looks like GitHub wiki will be used as the documentation source (markdown), it will still be processed into pretty html and pdf for armbian.com?
  15. Like
    miked got a reaction from Igor in Claim a task, set DUE date and start doing it!   
    I would totally do that! It might also identify some easy-to-fix problems that could be a good place to start contributing code.
  16. Like
    miked got a reaction from Tido in [Documentation] software proposal for Armbian wiki   
    I did a bit of experimentation and have the following suggestions:
     
    1. On http://www.armbian.com/change "Getting Started" to "Documentation". Currently all documentation is under "getting started" which isn't an intuitive place to look for advanced stuff.
    However since you want a clear "where to start" sign that stands out to new visitors, we could have a prominent "Getting Started: Everything you need to get Armbian up and running" icon/link/banner stickied near the top of the Home page (and maybe Downloads page if people are directly linked there from external sites). It should take you to a documentation page that starts with an outline (with links) of the main steps a complete novice would take.
     
    2. If the html docs are going to be mainly mkdocs output with some post-processing, I would try to put the output underneath the Armbian nav bar, using a theme that has the Documentation navigation on a left sidebar to avoid crowding the top. Theme readthedocs does this. It should be possible to use html <embed> to shove the mkdocs webpage into the Armbian web page. Unless someone really wants to tweak the theme and process the output to look perfect, maybe as little as changing the theme's colors will be enough to make it look good.
     
    Edit: That is, either you could let mkdocs use the whole browser window, which is not ideal because it looks like the documentation is a different site. Or leave mkdocs output as a full webpage and embed it, which I think would be easiest to try. Or process the output a lot so that you combine the Armbian page and the mkdocs output into one generated page, which should be more work but give you more control.
  17. Like
    miked got a reaction from lanefu in [Documentation] software proposal for Armbian wiki   
    I did a bit of experimentation and have the following suggestions:
     
    1. On http://www.armbian.com/change "Getting Started" to "Documentation". Currently all documentation is under "getting started" which isn't an intuitive place to look for advanced stuff.
    However since you want a clear "where to start" sign that stands out to new visitors, we could have a prominent "Getting Started: Everything you need to get Armbian up and running" icon/link/banner stickied near the top of the Home page (and maybe Downloads page if people are directly linked there from external sites). It should take you to a documentation page that starts with an outline (with links) of the main steps a complete novice would take.
     
    2. If the html docs are going to be mainly mkdocs output with some post-processing, I would try to put the output underneath the Armbian nav bar, using a theme that has the Documentation navigation on a left sidebar to avoid crowding the top. Theme readthedocs does this. It should be possible to use html <embed> to shove the mkdocs webpage into the Armbian web page. Unless someone really wants to tweak the theme and process the output to look perfect, maybe as little as changing the theme's colors will be enough to make it look good.
     
    Edit: That is, either you could let mkdocs use the whole browser window, which is not ideal because it looks like the documentation is a different site. Or leave mkdocs output as a full webpage and embed it, which I think would be easiest to try. Or process the output a lot so that you combine the Armbian page and the mkdocs output into one generated page, which should be more work but give you more control.
×
×
  • Create New...

Important Information

Terms of Use - Privacy Policy - Guidelines