Modern software documentation

Write markdown pages. Use a tool such as Visual Studio Code

Push via wiki, such Docusaurus

Using the same version/source control, such as Github

• Check-in/out for concurrent updates
• Versioning for comparison over time

Documentation is part of the product

A product has the lifecycle:

• Request via Jira
• Assign to an owner/creator
• when doc resource is a constraint, prioritize them
• Reviewed by PM, DEV
• Verified by QA
• Release via publishing
• Change/Correction, Enhancement via Jira

Browser Navigation

Useful keyboard shortcuts:

New Browser Window: Command + N (New)
Next Window in the same Apps: Command + key for [`~]
Previous Window in the same Apps: Command + Shift + key [`~] for reverse direction

New Tab: Command + T (Tab)
Close Tab : Command + W (Withdraw)
Move to Next Tab: Control + Tab (similar to command + tab for switching between apps)
Move to Previous Tab: Control + Shift + Tab for reverse direction
Go to the Address Bar: Command + L (Location)

Text Editors on Mac OSX

I used Text Mate and TextWrangler.  Both are excellent.  They are not really free and I do not want to have any license risk by using an unlicensed version for work.

I recently found a new alternative. 

The DEL key in Macbook

After I use MacBook for almost two years, I learn how to delete the character after the cursor.

MacBook tips : install Homebrew

MacOS Sierra
Version 10.12.6

This tool is useful. - https://brew.sh/

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Best Text Editor in Mac Book

I use TextMate.  I do not know if it is the best.  I like the following features:

Loading Data into Oracle database from SQL Developer

You do not need to write SQL loader script.  You do not need to create table first.
You just need to have the account in the database with the privileges, you can load the csv data into Oracle from SQL Developer.

Uploading the data file and creating schema are done in a wizard like UI.

Enable the ssh access to the Ubuntu VM running on Virtualbox from MacBook host

I have created a Ubuntu 64 bit VM on my macbook.  I enabled the ssh and sftp access to it.

The configuration involves the virtualbox VM setup as well as configuration within the linux.



Here are the steps:

Enable ssh and sftp access to Macbook

Sometime, it is useful to copy files from macbook or run the command line remotely or even from the VM.

I setup ubuntu VM using Virtualbox and use NAT network.  How to I access the host macbook?

Mac Pro without mouse

It took me a while to know how to do these:

• Scroll up and scroll down: swipe with two finger
• Right mouse click: two finger touch
• Back or forward to next page : swipe with two fingers

This video helps:

An online Markdown to HTML translator

This site is cool.

http://pandoc.org/try/?

Learning Markdown

"Markdown" is a specific markup language.

A markup language such as HTML allows us to put the formatting information to our text.

A doc or text created using markdown is actually the code that has to be interpreted to display nicely with the format we want.

The markup language, like HTML, is interpreted by the browser.   The text with markdown also needs to be interpreted by tools.

Some web site supports markdown:

• Wordpress.com - Markdown quick reference 
• Reddit
• Github
• Stack Overview

I found the Reddit markdown primer helps.

This is a short version.

► put returns between paragraphs
► for linebreak add 2 spaces at end
► _italic_ or **bold**
► indent code by 4 spaces
► backtick escapes `like _so_`
► quote by placing ">" at start of line

Here is an example of markdown text for link:


This is the [link][1] to metastore ER diagram. You might find the original [Hive paper][2] useful. I would also suggest you to browse through the official Hive documentation and read the good book `Programming Hive`.
[1]: https://issues.apache.org/jira/secure/attachment/12471108/HiveMetaStore.pdf
[2]: http://i.stanford.edu/~ragho/hive-icde2010.pdf


It generates:

This is the link to metastore ER diagram. You might find the original Hive paper useful. I would also suggest you to browse through the official Hive documentation and read the good book Programming Hive.

Communications in a software development organization

My experiences on these communication/ collaboration tool:

1. Email
2. Wiki
3. Instant Messaging
4. Phone
5. Audio Conferencing
6. Web Conferencing
7. Oracle Social Network
8. Collaboration Workspace
9. Group Calendar
10. Discussion Forum

Protect developers from unnecessary distrations

These are my favorite quotes from the book, Debugging the Development Process, from Steve Maguire:

"Any work that does not result in an improved product is potentially wasted or misguided effort."


"I've found that groups regularly get into trouble because programmers are doing work they shouldn't be doing. They're spending too much time preparing for meetings, going to meetings, summarizing meetings, writing status reports, and answering emails."

"The project lead should ruthlessly eliminate any obstacles that keep the developers from the truly important work: improving the product"

GTD Contexts

1. Someday/Maybe List

This is a Wish List.  If I have time I should spend some time on this task.
I still review it regularly to remind myself that I do not forget them.

This is different from the list that I will be regularly once a week on a specific scheduled time.

This is the list of tasks that I am not working on it.  The items listed here are unplanned lists.

It could be a project that still has not yet been broken down.

It can be a project idea.  They can be removed after researched and planned and the individual breakdown items ( not the whole item) are moved to other context category.

This a blog posting about Seven Problems with a Someday/Maybe List.

2. Special Occasions

I am assigning tasks to the future of me under some occasions.

Learn GTD

1. What is GTD

2. How to create a to-do list?

Summary

Three categories:

Use Wikidpad (3): Publish HTML pages

Although Wikidpad is personal wiki tool and does not really allow multiple users to update the wiki pages, Wikidpad can be a useful tool for generating HTML pages.

Use Wikidpad (2)

Where to Download the Wikidpad software?

You can find it in download.com.  Here is the specific Wikidpad Download page.

After I downloaded it, I got the WikidPad-2.1_01.exe file (7777KB) in my Downloads directory.

The WikiPad developer allows us to install the software in a portable form.  It means that we can install it into a USB drive.

It takes 25.5 MB from the disk after installing the software.

Getting Start with Wikidpad

It may confuse you after you open the Wikidpad first time.

It opens the WikidPadHelp wiki file, the help file itself written as a Wikidpad wiki file.

You can go ahead to create your first wiki file by click menu (Wiki -> New).

A dialog window "Create New Wiki" popup.

It asks you to enter a "WikiWord".   It is confusing again.

A wikiword is nothing but a term capitalized and connected without space.

You can enter "MyWiki" as a a start.  It will ask you where to save the file, like NotePad.

This step will create a file called "MyWiki.wiki".

How to create a wiki page in WikidPad?

You should see three wiki page already created for you:

• MyWiki
• ScratchPad
• WikiSettings

This is still confusing.

The MyWiki page is the wiki home page of your wiki workspace.  It supposes a wiki page that contains links to other pages.

The name "MyWiki" is coming from the name entered as the "WikiWord" when you create the wiki file.

ScratchPad page is a child page that is created by default under MyWiki page.  You cannot delete this page. 

To create a new page, you can simply enter another "WikiWord" in the ScratchPad page or the MyWiki page.

For example, you can enter "FirstPage" and click Ctrl-S to save the page.  You will notice that the FirstPage is created under the MyWiki or the Scratch page as another child page.

This behavior is similar to other wiki software.  You create a new page by creating a new link first.  The page name is the same as the title of the page without space.

Wikidpad makes an assumption that all "WikiWord" are links to a child page.  To turn off the behavior, you need to escape it by entering "\FirstPage".

Continue: Use Wikidpad (3): Publish HTML pages
Back:

Use Wikidpad (1)

What is Wikidpad?

Wikidpad is a desktop software that allows you to create a personal wiki.
A wiki publishes and shares the information. A personal wiki is for creating wiki pages that hold notes taken for yourselves.

I think that Wikidpad is really a note taking software.

Gnumeric

I have been using Gnumeric for several months.  Although people still use Excel, I have set Gnumeric as the main tool to open Excel file lately.

Excel for some unknown reasons cannot work together with the web conference system I am using.  A ridiculous workaround is that while I am using the web conference system, I have to open Microsoft Net meeting.  I guess some secret code from Microsoft only compatible with Net Meeting.

This is so annoying.  I do not really need any new advanced features from Excel 2007.  For me, Excel 2007 is a defect product if I can use an older version of Excel with web conference system without any problem.

I found that Gnumeric is actually faster than Excel in turn of opening the file and show data.

Almost all functions are compatible.